Add route middleware: auth, Throttle, ApiKey, IP filtering, HTTPS, CSRF, Honeypot and signed URLs by lmajano · Pull Request #74 · coldbox-modules/cbsecurity

lmajano · 2026-10-05T12:12:17Z

Description

Adds ready-made ColdBox route middleware so a route or a group can be secured where it is declared, without firewall rules. Parameters travel in the route meta() because a router file loads before modules.

Authentication middleware

route( "/account" ).middleware( "Authenticated@cbsecurity" ).to( "account.index" )

route( "/admin" )
    .middleware( "Authorized@cbsecurity" )
    .meta( { permissions : "ADMIN" } )
    .to( "admin.index" )

Authenticated@cbsecurity: logged in (ignores meta)
Authorized@cbsecurity: logged in and satisfying route meta permissions, roles and mode (any, all, none)
JwtAuth@cbsecurity / BasicAuth@cbsecurity: like Authorized, through those validators
Guard: base class for custom middleware

Denied requests go through the firewall's invalid access flow (redirect, override, block, module overrides, interception points, logging). Security gains public validateAccess() and processInvalidAccess(); the annotation path shares processInvalidAccess() with no behavior change.

Abuse protection middleware (new in this update)

They answer denied requests directly with a JSON error and status code. Defaults live in the new middleware and signedUrls module settings, every value can be overridden per route.

ID	Does	Route `meta()`
`Throttle@cbsecurity`	Rate limit, `429` + `Retry-After`, named or inline limiters, any CacheBox cache (default `default`)	`throttle`
`ApiKey@cbsecurity`	`x-api-key` header then `apiKey` request key (both configurable), keys or a validator service	`apiKeys`, `apiKeyHeader`, `apiKeyParam`
`AllowedIPs@cbsecurity` / `DenyIPs@cbsecurity`	IPv4, IPv6 and CIDR, `X-Forwarded-For` only from `trustedProxies`	`allowedIps`, `denyIps`
`EnsureHttps@cbsecurity`	`301` for GET/HEAD, `403` for other methods	`redirectToHttps`
`VerifyCsrf@cbsecurity`	cbcsrf token on unsafe methods	`csrfKey`
`Honeypot@cbsecurity`	Hidden trap field, silent `200` or `422`	`honeypotField`, `honeypotSilent`
`Signed@cbsecurity`	Only valid, unexpired signed URLs	none

New models: RateLimiter@cbsecurity (cache backed fixed window) and UrlSigner@cbsecurity (HMAC-SHA256 over path and query, optional expiration). New mixins: signedRoute(), signedUrl(), hasValidSignature(). A missing IP list or API keys throws cbsecurity.MiddlewareMisconfigured, a missing signing secret throws cbsecurity.SigningSecretMissing.

Requirements

Route middleware: ColdBox 8.2+.
Group-level meta and middleware inside execute(): ColdBox 8.3+ (COLDBOX-1459 Route middleware: run it in BaseTestCase.execute() and let group() share meta ColdBox/coldbox-platform#714, merged).
Named middleware aliases (registerMiddleware()): COLDBOX-1460 Add Router.registerMiddleware() for named closure, lambda and instance middleware ColdBox/coldbox-platform#719.

Type of change

New Feature
This change requires a documentation update (Document route middleware and add What's new 3.9.0 ortus-docs/cbsecurity-docs#29, Add Security section with cbsecurity guidance and best practices ortus-docs/coldbox-docs#302, Skills: route middleware, registerMiddleware(), group meta and middleware testing ColdBox/skills#20)

Checklist

cfformat applied to my files
I have commented my code
I have made corresponding changes to the documentation
I have added tests that prove my feature works
New and existing tests pass locally with my changes

Testing

BoxLang 1.18, TestBox 7.1, against the companion ColdBox changes: 212 passed, 105 of them in the two middleware specs (MiddlewareSpec 31, SecurityMiddlewareSpec 74). The 1 failure and 15 errors are pre-existing and all say "No default datasource" (this sandbox has no MySQL, JWT DB storage specs). Route specs skip themselves through feature detection on ColdBox without 8.3 behavior. I could not run Adobe, Lucee or ColdBox 7 locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E8yy4oK5vnaVucmYLg4UtY

Secure a route or a group where it is declared, with no firewall rules: - Authenticated@cbsecurity: the user must be logged in - Authorized@cbsecurity: logged in and satisfying the `permissions`, `roles` and `mode` (any|all|none) declared in the route `meta()` - JwtAuth@cbsecurity and BasicAuth@cbsecurity: Authorized, authenticating through the JWT or Basic validators - Guard: the base class for custom middleware Denied requests go through the firewall's invalid access flow, so redirect, override and block actions, module overrides, interception points and logging behave exactly like a firewall rule or annotation. The Security interceptor gains public validateAccess() and processInvalidAccess() methods for this; the annotation path now shares processInvalidAccess() with no behavior change. The route specs run only when the installed ColdBox can run route middleware in execute() and group meta (8.3+); the Guard specs run everywhere. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E8yy4oK5vnaVucmYLg4UtY

github-actions · 2026-10-05T12:13:25Z

lucee@5 ColdBox ^8.0.0 Test Results

1 files ± 0 9 suites +2 10s ⏱️ +3s
177 tests + 54 177 ✅ +54 0 💤 ± 0 0 ❌ ±0
228 runs +105 177 ✅ +54 51 💤 +51 0 ❌ ±0

Results for commit 8534bd8. ± Comparison against base commit a890b0c.